What is p-map?
The p-map npm package is a library that allows you to map over promises concurrently, controlling the number of promises that are running at any given time. It is useful for throttling asynchronous operations that are initiated in a loop, such as API calls, file operations, or any task that returns a promise.
What are p-map's main functionalities?
Concurrency Control
This feature allows you to control the number of promises that are executed concurrently. In the code sample, `pMap` is used to fetch a list of URLs with a concurrency limit of 2, meaning only 2 promises will be running at the same time.
const pMap = require('p-map');
const urls = [/* ... */];
const fetchUrl = async url => {/* ... */};
(async () => {
const result = await pMap(urls, fetchUrl, {concurrency: 2});
console.log(result);
})();
Error Handling
p-map provides options for error handling. In this example, `stopOnError` is set to false, which means that p-map will not stop mapping over the remaining items when one promise rejects. Instead, it will continue with the rest and collect all the errors.
const pMap = require('p-map');
const tasks = [/* ... */];
const doTask = async task => {/* ... */};
(async () => {
try {
const result = await pMap(tasks, doTask, {concurrency: 4, stopOnError: false});
console.log(result);
} catch (error) {
console.error('An error occurred:', error);
}
})();
Promise Cancellation
p-map supports promise cancellation when used with cancelable promises, such as those created with the p-cancelable package. This allows you to cancel the execution of the promises if needed.
const pMap = require('p-map');
const {CancelablePromise} = require('p-cancelable');
const tasks = [/* ... */];
const cancellableTask = task => new CancelablePromise(resolve => {/* ... */});
(async () => {
const mapper = cancellableTask;
const result = await pMap(tasks, mapper, {concurrency: 3});
console.log(result);
})();
Other packages similar to p-map
bluebird
Bluebird is a comprehensive promise library that includes a 'map' function with concurrency control. It offers a broader set of features for promise manipulation and is often considered a more heavyweight alternative to p-map.
async
The async library provides a wide range of functions for working with asynchronous code, including 'mapLimit' which is similar to p-map's functionality. Async is callback-based but also supports promises, and it is more general-purpose compared to the more focused p-map.
promise-map-series
promise-map-series is a simpler alternative that maps over a list of values in series, resolving promises one after the other, rather than controlling concurrency like p-map.
promise-pool
promise-pool is another library for handling multiple promises concurrently. It provides a pool abstraction that allows you to add tasks to a queue and process them with a controlled concurrency, similar to p-map but with a different API design.
p-map
Map over promises concurrently
Useful when you need to run promise-returning & async functions multiple times with different inputs concurrently.
Install
$ npm install p-map
Usage
const pMap = require('p-map');
const got = require('got');
const sites = [
getWebsiteFromUsername('https://sindresorhus'),
'https://ava.li',
'https://github.com'
];
(async () => {
const mapper = async site => {
const {requestUrl} = await got.head(site);
return requestUrl;
};
const result = await pMap(sites, mapper, {concurrency: 2});
console.log(result);
})();
API
pMap(input, mapper, options?)
Returns a Promise
that is fulfilled when all promises in input
and ones returned from mapper
are fulfilled, or rejects if any of the promises reject. The fulfilled value is an Array
of the fulfilled values returned from mapper
in input
order.
input
Type: Iterable<Promise | unknown>
Iterated over concurrently in the mapper
function.
mapper(element, index)
Type: Function
Expected to return a Promise
or value.
options
Type: object
concurrency
Type: number
(Integer)
Default: Infinity
Minimum: 1
Number of concurrently pending promises returned by mapper
.
stopOnError
Type: boolean
Default: true
When set to false
, instead of stopping when a promise rejects, it will wait for all the promises to settle and then reject with an aggregated error containing all the errors from the rejected promises.
p-map for enterprise
Available as part of the Tidelift Subscription.
The maintainers of p-map and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source dependencies you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact dependencies you use. Learn more.
Related
- p-all - Run promise-returning & async functions concurrently with optional limited concurrency
- p-filter - Filter promises concurrently
- p-times - Run promise-returning & async functions a specific number of times concurrently
- p-props - Like
Promise.all()
but for Map
and Object
- p-map-series - Map over promises serially
- p-queue - Promise queue with concurrency control
- More…